Conversation
|
|
Warning Review limit reached
Next review available in: 51 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (32)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c91bf4f5d7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <Update label="2026-07-23" description="Facets ship non-asset files; archive 0.2, per-file lockfiles, first-class README, and the 0.1 adapter contract" tags={["CLI", "Breaking", "New Feature"]} rss={{ | ||
| title: "Supplementary files, archive 0.2, and first-class README authoring", | ||
| description: "Facets can now declare and ship non-asset files: skill companion files (references, scripts, templates beside SKILL.md) that install and remove atomically with their skill, and top-level archive-only files like README.md and LICENSE that ship in the archive but never materialize on disk. Declare them with exact paths in the manifest's top-level files array or a skill descriptor's files array. Builds emit the new 0.2 archive format with a complete per-entry hash map; lockfiles move to 0.2 with a per-file integrity record for every materialized file; install reports and repairs drift per file. facet create now writes and declares an editable README.md by default (skip with --no-readme), and facet edit has a dedicated README panel. Consumers still accept legacy 0.1 archives and legacy alpha lockfiles during the compatibility window; the two versions are dispatched by exact match. Asset names are single-segment Agent Skills names -- slash-namespaced names are no longer valid in new manifests -- and skills and commands now share one namespace. The adapter contract advances from positional 0.0 to the tagged 0.1 request/result shape: rebuild and reinstall any adapter that still declares 0.0. Rollout is consumer-first: protocol, then registry, then adapters, then the CLI." |
There was a problem hiding this comment.
This publishes a July 23 “now” release announcement even though the same change leaves the held CLI release gate unfinished and adds no agent-facets changeset. Users of the released CLI will follow the documented --no-readme, archive 0.2, and adapter 0.1 migration paths before a CLI package exposing them exists. Keep this information in unreleased documentation, or add the <Update> with the final CLI release.
AGENTS.md reference: docs/changelog/AGENTS.md:L91-L109
Useful? React with 👍 / 👎.
| - **Command** — `commands/<name>.md`. A single markdown file whose content is the command's prompt. | ||
|
|
||
| YAML front matter in an asset file is optional. When present it MUST be preserved verbatim through the [build](/specification/build#steps); the manifest's `name`, `description`, and any per-adapter extras are merged on top of the author's front matter at install time. | ||
| A primary asset file (a `SKILL.md`, agent, or command file) MUST NOT contain YAML front matter — the manifest is the single source of asset metadata. Authoring tools strip front matter before writing, and [`facet build`](/specification/build#steps) rejects a primary file that still carries it. |
There was a problem hiding this comment.
This new normative rule is the opposite of the implementation: validateContentFiles only rejects empty prompts, and runBuildPipeline explicitly permits author front matter before preserving it for install-time metadata merging. Existing facets with YAML headers therefore still build and install correctly, while these docs instruct their authors to remove valid content and adapter metadata. Restore the allowed-front-matter documentation, or land the corresponding enforcement before documenting this as a breaking change.
Useful? React with 👍 / 👎.
|
a738ae8 to
d2de027
Compare
7c8b3c1 to
b48fb4b
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b48fb4b4ea
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <ResponseField name="--no-readme" type="boolean"> | ||
| Skip the default `README.md`. `facet create` writes and declares an editable `README.md` (seeded from the name and description) by default; pass `--no-readme` to scaffold without it. |
There was a problem hiding this comment.
--no-readme trigger headless scaffolding
When users run facet create --no-readme without another content flag, this documentation promises that the README will be skipped, but decideCreate deliberately leaves readme out of HEADLESS_FLAGS and its test confirms that this invocation opens the default README-enabled wizard instead. Either include --no-readme in the headless trigger set or document that it only takes effect alongside headless content flags.
Useful? React with 👍 / 👎.
Merge activity
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a2958c5. Configure here.
| const sibling = type === 'skill' ? 'command' : type === 'command' ? 'skill' : undefined | ||
| if (sibling && assets[sibling].items.some((item) => item === value)) { | ||
| return `"${value}" is already used by a ${sibling} (skills and commands share one namespace)` | ||
| } |
There was a problem hiding this comment.
Headless create skips namespace check
Medium Severity
This commit adds shared skill/command namespace validation to the create and edit wizards via validateAssetNameInWizard, but headless facet create still only runs validateAssetNameSegment per type, so the same colliding --skill and --command names can scaffold successfully and fail later at build.
Reviewed by Cursor Bugbot for commit a2958c5. Configure here.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a2958c5e93
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <Note> | ||
| `facet modify` operates on asset primaries. To adopt, move, or reconcile a skill's [companion files](/specification/manifest#supplementary-files) or top-level supplementary files, use [`facet edit`](/cli/authoring/edit). | ||
| </Note> |
There was a problem hiding this comment.
facet edit
For a skill that has declared companions, facet edit cannot move those files during a rename: its edit session treats the renamed skill as a new scaffold plus deletion of the old skill and its declared companions (use-edit-session.ts builds those operations), and reconciliation only offers add/ignore or scaffold/remove actions. Thus the newly documented instruction sends users to a flow that cannot preserve or relocate companion content; document a safe manual move sequence or implement companion-aware renaming before recommending this command.
Useful? React with 👍 / 👎.
…t-name constraints, and adapter API `0.1` migration
…ose scenario-coverage test gaps (16.4) Scenario-by-scenario verification of the support-non-asset-files delta specs surfaced findings, resolved here: - Front-matter delta relaxation: the authoring specs required build to reject primary-asset front matter and edit to parse/strip it, but the implemented (and pre-existing) contract permits author front matter, archives it verbatim, and reconciles manifest-owned metadata over it at install time. Relaxed the build, 'manifest is source of truth for metadata', and edit requirements to match the implementation, and corrected the design.md drift-checking rationale. - Wizard shared-namespace validation: create and edit wizards validated within-type duplicates but not the skill/command shared namespace. Extracted a shared validateAssetNameInWizard helper, wired both views to it, and added unit coverage. - Missing-arm tests: added a RECONCILE_OWNED_PATH_SET run-install test and a single-file command lockfile-entry test. - Archive-format compatibility mapping: MINIMUM_RELEASE_FOR_FORMAT['0.2'] set to the projected activation release 0.31.0, with its test updated. The held agent-facets CLI activation Changeset is intentionally NOT here; it lives in a separate held draft PR stacked on top.
a2958c5 to
144bb0e
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 144bb0ed00
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| <ResponseField name="--skill / --agent / --command" type="repeatable"> | ||
| An asset to scaffold. Repeat per asset; at least one is required in headless mode. Asset names must be kebab-case. | ||
| An asset to scaffold. Repeat per asset; at least one is required in headless mode. Asset names are single-segment [Agent Skills names](/specification/manifest#asset-names); a skill and command can't share a name. |
There was a problem hiding this comment.
The documented shared namespace is enforced only by the interactive wizard. In headless mode, decideCreate validates each flag group independently and passes both arrays to writeScaffold, so facet create --name demo --skill review --command review succeeds but writes a manifest the current schema rejects; the user's immediately scaffolded project then cannot build. Add a cross-check before returning the headless options (or avoid promising this constraint for headless creation).
Useful? React with 👍 / 👎.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| 1. **Parse and validate the manifest.** Read the facet manifest (`facet.json`) and validate it against the [manifest schema](/specification/manifest). Invalid manifests MUST be rejected with a descriptive error. The manifest's `name` MUST be a valid facet identity; the `version` MUST be a semver string; at least one text asset MUST be declared. | ||
|
|
There was a problem hiding this comment.
The user-facing docs in this PR consistently say primary asset front matter is a build error: this file (step 2), docs/specification/manifest.mdx ("rejects a primary file that still carries it"), docs/changelog/index.mdx ("is now a build error"), and docs/guides/create-your-first-facet.mdx ("MUST NOT carry YAML front matter"). However, both internal spec files updated in the same PR say the opposite. openspec/changes/support-non-asset-files/specs/authoring__facets/spec.md now reads: "Author-supplied YAML front matter in a primary asset file SHALL be permitted: build SHALL preserve it verbatim in the archive, and materialization SHALL reconcile it with the manifest by merging manifest-owned metadata on top of any author front matter." openspec/changes/support-non-asset-files/design.md likewise says "Author-supplied front matter in a primary asset is archived verbatim."
One of these two authoritative sources is wrong. If the implementation rejects front matter at build, the OpenSpec misleads contributors; if it preserves and merges it, the user-facing docs and changelog tell authors to expect a build error they'll never see. The PR description's own Cursor summary note flags this: "OpenSpec authoring deltas now say primary front matter is archived verbatim and reconciled at install (while much of the new user-facing changelog still describes front matter as a build error—worth aligning)." This should be resolved before merging so that docs and spec agree on the actual runtime behavior.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
Why
Facets previously shipped only their declared assets. This documents the new ability for facets to declare and ship non-asset files — skill companion files that install and remove atomically with their skill, and top-level archive-only files like
README.mdandLICENSEthat travel inside the archive but are never written to disk at install time.Details
The documentation updates cover several interconnected breaking changes shipping together:
Supplementary files. The manifest's top-level
filesarray declares archive-only files (README.md,LICENSE, etc.). A skill descriptor's ownfilesarray declares companion files (references, scripts, templates) that materialize atomically with the skill. Both are declared as exact paths — no globs. Top-level paths cannot resolve underskills/, and a skill's companions cannot listSKILL.mditself.Archive
0.2and lockfile0.2. Every build now emitsfacetVersion: 0.2with a complete per-entryfileshash map covering every archive entry. The lockfile moves to0.2with a per-file{ path, integrity }record inside each asset entry. Consumers accept legacy0.1archives and legacy alpha lockfiles during the compatibility window; versions are dispatched by exact match, never numeric ordering.Asset naming. Asset names are now single-segment — slash-namespaced names like
viper-plans/planningare no longer valid in new manifests. Skills and commands share one namespace and cannot reuse a name. Companion file paths may contain/for directory depth, but that is path depth, not part of the asset name.No front matter in primary files. A
SKILL.md, agent, or command file carrying YAML front matter is now a build error. Asset metadata lives exclusively in the manifest.Adapter API
0.0→0.1. The adapter contract advances to a tagged multi-file request/result shape. A0.1CLI treats a0.0adapter as unsupported and fails before any write.First-class README authoring.
facet createwrites and declares an editableREADME.mdby default (skip with--no-readme).facet editgains a dedicated README panel for creating, adopting, editing, or removing bothREADME.mdand the extensionlessREADME.Rollout order. The change ships consumer-first: protocol package publishes dual
0.1/0.2verification, then the registry adopts it, then adapter SDK and first-party adapters publish0.1, then the CLI release turns on0.2production.The three version axes — adapter API, archive
facetVersion, and lockfile version — are independent and classified separately. A0.0adapter fails on the adapter axis before a facet'sfacetVersionis even examined.Verification
Documentation tasks 14 and 15 are marked complete in the task tracker. Compatibility and release-order claims were verified against authoritative schemas, constants, package metadata, and staged Changesets.
Note
Medium Risk
Mostly documentation and small CLI validation, but the release bundles breaking contract changes (0.2 formats, naming, adapter 0.1) and the front-matter story is inconsistent across pages in the same PR, which could mislead authors until reconciled.
Overview
This PR documents and tightens the non-asset-files release: facets can declare top-level archive-only files and per-skill companions, builds/installs use archive and lockfile
0.2(per-entry hashes, per-file lock records, atomic skill bundles), and adapter API0.1is called out as a separate compatibility axis from archive/lockfile versions.Documentation updates span the root README, a large 2026-07-23 changelog entry, specification pages (archive, build, manifest, lockfile, commit, install, integrity, publish, terminology), and authoring/install guides (
create/editwith defaultREADME.mdand--no-readme, troubleshooting for unsupported archives and per-file drift). OpenSpec design and authoring deltas move primary-asset YAML front matter from “strip/reject at build” toward preserve in the archive and reconcile from the manifest at install; note that some user-facing spec/changelog lines in the same diff still describe front matter as a build error, so reviewers may want those aligned.CLI behavior in this diff: create/edit wizards share
validateAssetNameInWizard, enforcing single-segment names and skills/commands sharing one namespace (agents stay separate).archiveCompatibilityGuidancemaps unsupported format0.2to minimum CLI0.31.0.Engine/protocol touch-ups: regenerated registry OpenAPI client (contents responses expose a
fileslist instead ofresources), arunInstalltest forRECONCILE_OWNED_PATH_SETwhen the lockfile lists owned paths the plan does not, and lockfile schema tests for agent/command primary paths. OpenSpec tasks 14–15 and part of 16 are marked complete; registry/adapter publish verification items remain blocked.Reviewed by Cursor Bugbot for commit 144bb0e. Bugbot is set up for automated code reviews on this repo. Configure here.